How to employ and write simple formulas

• perform mathematical and date/time operations
• make decisions
• format text, lists and tabular data

Where formulas can be used

Document templates

In document templates, formulas can be used in the Formatting rules for any field in the document. The Evaluate a formula rule is where you enter the formula. The formula may contain any of the available constructs, referring to the variable 'x' to access the data that is to be inserted into the field. You can use the Assign to a variable rule on one of the components of a composite field to make other values available to the formula. (Note that assigning a value to a variable causes it not to appear in the field in the document.) You can apply additional formatting rules to the value in the field before it is assigned to the variable; the rules are applied from top-to-bottom.

As mentioned above, the order in which the formula appears is significant. If the formula appears in a component of a composite field, it applies only to that component and is evaluated separately for each result (if there are multiple). If the formula appears before an aggregation rule, it is evaluated for each result after the components of the composite field have been joined together. If the formula appears after an aggregation rule, it is evaluated only once and the variable 'x' will refer to the value after the results have been combined.

Example:

1. Create a field in the template which maps to the date of the document (Document.Dates.(Primary).Date).
2. Click the 'Rules & formatting' button next to the field entry in the grid.
3. Click 'Add' and select 'Evaluate a formula' from the dropdown.
4. Enter the following formula: AddDays(x, 7)
5. Click OK and then save and close the template.
6. When generating the document, the field should populate with a date that is 7 days after the date of the document.

Description expressions

Formulas can also be used in description expressions, although it is recommended to use the built-in constructs for decision-making and text formatting in preference to the equivalent features in formulas. However, they are still useful for mathematical and date/time operations.

Unlike document template fields, where there is already an input value and a variable 'x', you must explicitly assign values to all variables that will be referenced within your formula. You can assign any value that would otherwise appear in the description expression by selecting the Assign to a variable type from the dropdown, choosing a variable name and then adding the value. You should place these parts of the expression at the beginning (expressions are built from left-to-right). Then, at the position in the expression where you want to evaluate the formula, select the Evaluate a formula type from the dropdown and enter the formula.

Example:

1. Open the description builder for a document type of your choosing. Ensure that a date (in this example, 'Expiry') has been added to the document type.
2. Enter the following expression and click Parse: [Assign(x,[Date:Expiry])] Old passport for [Client] - expired [Evaluate(Age\(x\))] years ago
3. Note the composition of the tree; in particular those parts which pertain to the formula.
4. Click OK and then save and close the document type editor.
5. When cataloguing/creating a document using this type, the description should contain the number of years by which the passport has expired.

Interactive forms

The Interactive Forms Framework fully integrates simple formulas into its rule system; any value appearing in the conditions or actions for a rule can be specified as a formula.

As with description expressions (above), there is no implicit variable 'x' upon which formulas on interactive forms can operate; therefore, every formula includes declarations for the variables that will be referenced (these are appended to the formula by the editor). Any value can be assigned to a variable, although in practice you are most likely to specify a record or control.

To distinguish formulas from other types of values, they are prefixed with an equals sign (=); this is done automatically by the editor and does not need to be typed by the user.

Example:

1. Create or open an interactive form design.
2. Add two date fields, 'dateField1' and 'dateField2'. Set the Required property on both fields to 'Yes'.
3. Click Page Rules on the toolbar and add a new Unconditional rule.
4. Add a 'Set value' action and specify 'dateField2' in the first box.
5. Click the button next to the second box and change the value type to 'Formula'.
6. Enter the variable name 'd' into the first column of the grid and 'dateField1' into the second column.
7. Enter the following formula: AddYears(d, 1)
8. Click OK on all popup windows until you return to the form designer.
9. Upon previewing the form, you will see that changing the first date picker will cause the second date field to show the same date next year.

Advanced users note: Interactive form rules additionally allow formulas to be used to construct the names of records and controls, via the 'Dynamic evaluation' option. This feature is useful if you want to retrieve or update the value of an object on the form whose name is not known at design-time; for example, selecting a different text field depending on the user's previous answers, or accessing related records inside a For-Each rule.